Python AI coding Automation Workflow

A Timeout Is Not a Rollback: Check Before Retrying an Agent Command

The Prompt Shelf ·

An assistant reports that a command timed out and offers to run it again. Before accepting, find out whether the first attempt stopped—and what it already changed. A deadline expiring is a different event from a process terminating. Termination is different again from undoing a file write.

We tested these distinctions with synthetic Python processes on macOS. In one case, a descendant wrote a file after its parent had been killed. In another, a file written before termination remained afterward. These results concern local process behavior, not a measured failure of an AI product’s cancel button.

Four questions before retrying

QuestionEvidence you need
Did waiting end?The specific API’s timeout result
Did the directly started process stop?Its observed termination status
Did the relevant downstream work stop?The supervisor’s result for the work it owns, including delegated work where applicable
Were earlier changes undone?An explicit check of outputs or the application’s rollback result

Do not turn a “yes” in one row into a “yes” in the next. A retry that writes files, submits a job, or changes a database can duplicate work even when the earlier process is no longer running.

This article applies to a local command whose launch and output locations you control. It is not a recipe for finding and killing arbitrary processes on your computer.

What the Python APIs mean

The Python 3.14 subprocess documentation distinguishes waiting from cleanup. Popen.wait(timeout=...) raises TimeoutExpired when the wait expires. Popen.communicate() has its own timeout and pipe-handling instructions. The higher-level subprocess.run(timeout=...) kills and waits for its child before re-raising a timeout; that is not the API tested below.

On POSIX systems, terminate() sends SIGTERM, while kill() sends SIGKILL. On Windows, the implementation differs and kill() is an alias for terminate(). Do not transfer the macOS results to Windows unchanged.

The signal documentation describes signal handlers and their limitations. Sending an ordinary termination request does not by itself show that the target has finished.

What we actually ran

On November 8, 2026 JST, we used Python 3.14.3 on macOS. Each fixture used an isolated temporary directory and newly created Python processes. Standard streams went to DEVNULL, so these tests do not exercise pipe-buffer handling. No real repository, customer file, network service, or database was modified.

The first fixture launched a parent that launched a short-lived child. The child wrote a readiness marker, waited 0.8 seconds, and then wrote a second synthetic marker. After readiness, the harness called Popen.wait(timeout=0.05) and handled the timeout explicitly.

CaseAction after readinessObserved result
Stop the directly started parentKill the parent and wait for itParent exited with -9; its child subsequently wrote the marker
Stop the fixture’s own process groupSend SIGKILL to the new group created for this fixtureParent exited with -9; the later marker was absent
Child ignores SIGTERMSend termination request, then wait 0.15 secondsWait expired; an explicit kill ended the child with -9
Child has already written a fileKill the child after a readiness markerChild exited with -9; its earlier file content remained

These four cases were executed once across two local experiments. Writing this article did not rerun them or count them as new results. Readiness markers separated process startup from the behavior being tested; the short deadlines are fixture choices, not production timeout recommendations.

The group experiment used start_new_session=True for a group created by the harness itself. Python documents this POSIX session behavior; os.killpg sends a signal to a specified process group. That does not mean every descendant of an arbitrary command will remain in that group. Detached children, separate sessions, containers, and remote jobs were not tested.

The harness cleaned up only its own processes and temporary files. We are not presenting its force-kill operation as a general production cancellation policy. Forced termination can prevent normal cleanup, and an absent marker does not establish that every possible side effect was prevented.

A practical retry decision

1. Identify the command and its outputs

Ask what the assistant started, how it started it, and where it could write. Distinguish an external executable from a shell wrapper and from a request submitted to a remote service. If that information is unknown, automatic retry is premature.

Record the expected output and any existing result from the first attempt. A partial output is evidence to inspect, not automatically a file to delete.

2. Use the application’s supported stopping mechanism

A development server, job supervisor, or service may provide a specific stop command and status check. Prefer that documented lifecycle over guessing a PID from a process name. Confirm that you own the target and understand the stop operation’s scope.

If a normal stop request exceeds its grace period, record the unresolved state. Do not silently escalate to a machine-wide kill or start another copy of the job. The correct next step may be a supervisor-level check or help from the process owner.

3. Check changes separately from process status

After confirmed termination, inspect what the attempt already produced. Our fourth case demonstrates the smallest version of this problem: a completed file write survives termination.

For a database or external request, use that system’s transaction, job-status, and duplicate-prevention mechanisms. This experiment did not test them. A process exit code cannot establish whether a remote request committed.

4. Decide whether another attempt is safe

Retry only when the relevant work has a known state and the operation’s duplicate behavior is understood. “Safe to repeat” might come from a documented idempotency mechanism, an application rollback, or an authorized review of outputs. It does not follow from a timeout alone.

A concise report can say:

Wait outcome:
Direct process termination:
Downstream work status:
Outputs or changes already present:
Duplicate-prevention or rollback evidence:
Retry decision and remaining unknowns:

Leave an unknown field unknown. Do not replace it with “cancelled” because an interface stopped waiting.

Tool choice and limits

The local checks used standard Python APIs and did not require a paid tool. If you are selecting an automation product, ask how it reports downstream work, handles interrupted operations, and prevents duplicate submissions. Test those requirements in an authorized disposable environment before treating a timeout feature as sufficient.

We did not establish that any paid assistant or orchestration product solves these problems. Reader demand, time saved, and purchase outcomes are unmeasured. The practical value here is a more precise acceptance criterion for automation.

For a different boundary—whether a completed pipeline hid a producer or logger failure—see the Bash and tee exit-status guide. You can put the retry questions into your project instructions using the rules gallery. Neither guide certifies that an arbitrary operation can be stopped or reversed safely.

Related Articles

Explore the collection

Browse all AI coding rules — CLAUDE.md, .cursorrules, AGENTS.md, and more.

Browse Rules