Prospero’s useful timeout trick: keep the command, return a handle

A build takes longer than the agent expected. The tool says “timeout.” The agent starts the build again.

Except the first build is still alive. Now both are writing into the same directory. Excellent. A distributed system, accidentally. 🫠

That failure is why the part of Prospero that caught my attention is its command lifecycle. Chris Wellons’s new native coding harness describes a specific transition: when a foreground command outlasts its wait, it becomes a background job the agent can still identify.[1]

Original explanatory diagram of the documented lifecycle. This is not a captured Prospero session.

The wait ended. What happened to the work?

“Timeout” is an incomplete answer. It could mean the process was terminated, the caller stopped waiting, or a request failed while the remote work continued.

Those outcomes need different next actions. Retrying makes sense after a confirmed failure. It can duplicate work when the original process is merely slow.

Prospero’s shell-tool description makes that distinction explicit. A running command becomes a job after its foreground timeout. The agent is told when that job ends; it can read output or stop the job through separate tools.[2] 🔎

The useful object is the handle: a continuing reference to the work already started. A transcript that says only “timed out” loses that reference at precisely the moment it becomes valuable.

This also changes the meaning of progress. “Still running, attached to this job” is an actionable result. It should not be turned into “failed” merely because the tool call has returned.

There is an inspectable contract behind the announcement

I followed the announcement into the shell-tool source and its tests. The source names job_output and job_kill; the latter is described as stopping the job and the processes it started.[2]

The test file includes expected messages for a command moved into a job, a user moving it into the background, and the failure case where there is no room for another job.[3] That last case matters: background execution has capacity limits too.

These are source observations. I have not run Prospero or its test suite, and I am not claiming that reading a test proves process cleanup on every supported platform.

💡 The design gives the model a more precise vocabulary: running, completed, failed, or stopped. “The tool returned” is not itself one of those process outcomes.

Stopping needs its own meaning

Wellons also describes keeping the process tree together when stopping a command.[1] That addresses the other half of the problem: terminating a wrapper while its compiler, test worker or development server survives.

The practical review question is therefore broader than “does the stop button respond?” It is: which descendants still exist after cancellation, and can they keep modifying the workspace?

That is a question to test in a disposable project. A successful exit in the transcript is not a census of surviving processes.

⚠️ The common mistake is to treat a wait limit as a cleanup guarantee. Prospero’s documented promotion to a job deliberately means the work continues. Explicit cancellation and natural completion are separate paths.

Why this is more interesting than another interface debate

Prospero has a native GUI and connects to a separately supplied model provider.[4] Those choices explain its packaging. The command contract explains how an agent might recover from an ordinary slow build without starting a competing copy.

The same concern appears in Danil Galeev’s DEV article about agent cleanup: command limits, session deadlines and workspace lifetime are separate responsibilities.[5] That distinction helped frame my reading here. Preserving a job handle solves one ownership problem; it does not decide when an entire workspace should expire.

✅ My takeaway from the source is a small acceptance criterion for coding tools: after a wait expires, the next action should operate on the existing command, with its identity and outcome still visible.

The interesting unit is the piece of work that survives the conversation turn.

References and figure

1. Chris Wellons: Prospero announcement.
2. Prospero shell and job tools, inspected revision.
3. Prospero tool-result tests, same revision.
4. Prospero README.
5. Danil Galeev: The agent finished. Who turns off the VM?.

Lifecycle diagram: original illustration; arrows describe documented states, not measured timings.

AI disclosure

AI was used to draft the article.