# Stopping and restarting a run

A run is one stretch of the agent's work on a session, such as drafting the plan or building it.
You can stop a run that heads the wrong way and correct the agent, or cancel the session and come
back to it later. When a run fails or stops responding, the session says why, and you can retry it
or restart it.

<Availability permission="Sessions: Update to stop, cancel, resume, retry and restart runs." />

## Key concepts

**Run.** One stretch of work by the agent: drafting the plan, building it, or handling a message
you sent. While a run is in progress, the session's status icon in the **Code** list is orange,
with a soft light circling it.

**Failed.** The status of a session whose run stopped on an error. The session shows the error,
with **Retry**.

**Cancelled.** The status of a session that was cancelled: by someone who chose **Cancel session**,
or by Productmind, for example when its pull request was closed. Its plan, conversation and branch
are kept.

## The controls at a glance

Three controls stop the agent, and each acts on one thing:

| Control | Where | What it does | The session afterwards |
| --- | --- | --- | --- |
| **Stop turn** (a square) | In the conversation's composer, while the agent works | Stops what the agent is doing now | Stays open: your next message carries on from where the agent stopped |
| **Stop preview** (a square) | Beside the running preview, at the top of the document | Shuts down the live preview, and the agent's current step if it is working, after pushing their unsaved changes to the working branch | Stays open: **Start preview** brings the preview back |
| **Cancel session** (an X) | In the page header | Ends the session's run, once you confirm | **Cancelled**: go back with **Resume session** when there is something to resume, start again with **Draft a new plan**, or mark it completed |

Point at a control to see what it does.

## Stopping a run

### To stop the current step and correct the agent

1. While the agent works, choose **Stop turn** in the conversation's composer.
2. Type what the agent should do instead, and send it.

Until the agent has stopped, the button spins and reads **Stopping the turn...**. The session keeps
running. The agent picks up where it stopped, with your correction: a stopped plan draft carries on
and asks for your approval, and a stopped build carries on to its pull request.

While the plan is drafted, the conversation is the session's document, so you stop and correct the
draft right there. Once the agent has stopped, the document says **You stopped the agent while it
drafted the plan**: type what to change in the box below it, or choose **Continue drafting** to
have the agent carry on where it stopped. Either way the conversation is kept.

Messages you queued are kept: the first one is sent as soon as the agent stops, and the rest follow
one at a time. See [To send a message while the agent works](/user-guide/sessions/working-in-a-session#to-send-a-message-while-the-agent-works).

Changes the agent made in the step you stopped aren't pushed to the working branch. They stay on the
machine running the session, and your correction carries on from them. With
[Push work in progress](/user-guide/settings/workspace-settings/coding-sessions#how-work-in-progress-behaves)
on, the steps the agent finished are already on the branch.

In a session that builds on the cloud, that machine is the session's runner. Once the runner leaves,
a few minutes after the session goes idle, the stopped step's changes are gone, and the agent
carries on from the working branch. See
[How a running session behaves](/user-guide/sessions/working-in-a-session#how-a-running-session-behaves).

While a live preview runs, a stopped step's changes stay in the preview until it stops: before
it goes, they are pushed to the working branch, whether you choose **Stop preview** or the preview
stops on its own.

To stop only a live preview, choose **Stop preview** beside it. See
[Live preview](/user-guide/sessions/live-preview#to-stop-the-preview).

:::note
If the agent doesn't respond to **Stop turn**, the session is marked **Cancelled** after a few
minutes, and says **The agent didn't respond to Stop turn, so the session was cancelled.** To end
it at once, choose **Cancel session** in the page header.
:::

### To cancel the session

**Cancel session** shows in the page header while the agent works, while it waits for your answer
to a question, and while its agent is offline.

1. Choose **Cancel session** in the page header.
2. Read the confirmation. Under **Cancel this session?**, it says, for this session, what stops,
   what's kept, whether a question the agent asked is closed, what happens to its tasks and bug
   reports, and how many of your queued messages won't be sent.
3. Choose **Cancel session** to confirm, or **Keep session** to go back.

The agent stops, any preview stops, and the session becomes **Cancelled**:

- **The plan, the conversation and the branch are kept.** Work already pushed to the working branch
  isn't affected. Changes the agent made in the step you cancelled, and hadn't pushed yet, are
  discarded.
- **Pull requests stay open.** Merging one later doesn't complete the session.
- **Tasks and bug reports keep their status.** A task that is **In Progress** stays **In
  Progress**. They stay in the session, and a new session can take them on.
- **A question still waiting for an answer is closed.**
- **Messages you queued aren't sent.** Each one shows **Not sent**, with **The session was
  cancelled.**

The session then shows **Session cancelled**: **The plan, the conversation and the branch are
kept. Draft a new plan to start again, or mark the session completed if the work is done.** When the
session has no plan yet, it starts with **The conversation and the branch are kept.** When the
session can be resumed, the notice names **Resume session** first, for example **Resume the session
to go back to its open pull requests, or draft a new plan to start again.**, and the confirmation
before the cancel doesn't say it can't be undone. When the session was cancelled by something other
than a person's choice, the notice also says why:

| The notice says | Because |
| --- | --- |
| **The agent didn't respond to Stop turn, so the session was cancelled.** | The agent didn't acknowledge **Stop turn** within a few minutes. |
| **Its pull request was closed. Reopening it puts the session back PR Ready for Review.** | A pull request of the session was closed without merging. Reopen it to go back to **In Review**. |

The session's sandbox and plan can be edited again, and so can its repositories, tasks and bug
reports, as at any time before the session is completed. To start again, choose
**Draft a new plan**: after you cancelled a plan draft, it picks up where it left off, and the
button reads **Resume planning**. After you cancelled a build, the new plan starts from scratch. A
plan drafted from a [Code conversation](/user-guide/sessions/starting-a-session#code-conversations)
is drafted again from that conversation, until you approve a plan. If
the work is done, choose **Mark as completed** instead. See
[Completing a session](/user-guide/sessions/overview#completing-a-session).

### To resume a cancelled session

A cancelled session shows **Resume session** when it has something to go back to, with **Draft a
new plan** beside it. The line under **Resume session** says what it does:

| The line says | When | What Resume session does |
| --- | --- | --- |
| **Back to review with its 2 open pull requests.** | At least one of the session's pull requests is still open | Puts the session back **PR Ready for Review** with its pull requests. Nothing runs. |
| **Continues the build where it stopped, in the same conversation.** | You cancelled the build of an approved plan before it opened a pull request, and the plan hasn't changed since you approved it | Starts the build again from where it stopped, in the same conversation with the agent and from what it had pushed to the working branch. |

1. Choose **Resume session**.

Resume session never runs the step you cancelled again. For example, if you cancelled the agent
while it was bringing a pull request up to date with its target branch, the session goes back to
**PR Ready for Review**, and you can run that step again from the pull request.

When you cancelled a build and then changed the plan, the session shows **The plan changed since it
was approved: draft a new plan to approve it again.** and no **Resume session**. When every pull
request of the session was closed or merged, there is nothing to resume: reopen a closed pull request
to put the session back **PR Ready for Review**, or mark the session completed.

If your organization's billing or settings refuse the build, the session stays **Cancelled**, and
the message says why.

If Productmind can't push to one of the session's repositories, **Resume session** is grayed out
when it would continue the build, under **Resume is held until Productmind can push**. The notice
says why for each repository and what to do. Once that's done, choose **Check again**. **Draft a
new plan** stays available.

## Recovering a run

### To recover a failed run

When a run fails, the session shows the error it stopped on: what went wrong, why, and what to do.
Choose **View details** to read the error's output in the **Errors** tab (see
[Reading the session's errors](/user-guide/sessions/working-in-a-session#reading-the-sessions-errors)). Below the error are two choices:

- **Retry** runs the same step again, for example after you fixed what made it fail. If it can't
  be retried, point at **Retry** to see why. When a build failed because your Git provider refused
  its push, the agent is told why the push was refused, and pushes the changes the session kept. See
  [Who opens the pull requests](/user-guide/sessions/pull-requests#who-opens-the-pull-requests).
- **Cancel session** opens the same confirmation as the page header's, which says **The failed run
  can't be retried after this.** Once you confirm, the session is **Cancelled** and keeps any drafted
  plan. Choose **Draft a new plan** to start again.

When a run that was changing code fails, for example because the AI model reached a limit or the
agent ran into an error, the agent's unfinished work is saved to the session's working branch before
the run ends. Retry continues from that work, in the same conversation with the agent, instead of
starting over, whether it runs on the same runner or on a new one:

- **A build.** The error names the branch, for example **Your unfinished work was saved to
  session/ssid-6-2026-10-06-101530. Retry continues from it.** The pull request isn't opened yet:
  the session shows **Work in progress saved** where its pull requests will appear, and the build
  you retry opens it when it's done.
- **A fix on an open pull request**, for review comments or for failing checks. The unfinished fix
  is pushed to the pull request, so its reviewers see a work-in-progress commit, and its checks run
  on it. The error says **Retry re-applies the review comments still open, continuing from the pull
  request's branch.** If no review comment is left open, Retry puts the session back **PR Ready for Review**
  and runs nothing.
- **A change you asked for in the conversation.** It can't be retried, so the session shows no
  **Retry**. It says **This run was a message you sent, so it can't be retried. Send it again in the
  conversation, or send a new instruction.**, with **Open conversation** and **Cancel session**.
  Choose **Open conversation**, then send your message again (press the Up arrow in the empty
  composer to bring it back) or a new instruction. The agent continues from the work it saved, and a
  change to an open pull request is pushed to it. If you choose **Cancel session** instead, its
  confirmation says **The conversation won't take your message again after this.**

When a plan fails, **Retry** continues it in the same conversation with the agent instead of
drafting a new plan. If you had asked for changes to the plan, the agent gets the comments still
open on it again, and the error says **Retry sends the comments still open on the plan again,
continuing the revision in the same conversation.** To start the plan over instead, choose
**Cancel session**, then **Draft a new plan**.

A build you retry follows the plan as it reads now. Editing the plan after the run failed doesn't
hold **Retry** back. When the agent continues the work it saved, it's told if the plan changed since
it started that work.

If billing refused the run, nothing ran and nothing was charged, so the session shows a warning
instead of an error: **Waiting for billing**, the reason and the action that fixes it, such as
**Top up**, with **Resume** in place of **Retry**. Once the cause is fixed, the session reads
**Billing is ready. Resume to continue.** Choose **Resume** to run the step. See
[If a session is refused on billing grounds](/user-guide/sessions/starting-a-session#if-a-session-is-refused-on-billing-grounds).
For a change you asked for in the conversation, it reads **Billing is ready. Send your message
again to continue.**

If the run stopped because the AI model reached its usage limit, the session shows a warning instead
of an error: **Paused: model capacity is used up**, with the time the limit resets, in your local
time. For example: **This session's model capacity is used up until Nov 1, 2026 1:00 AM. Resume the
session then.** Choose **Resume** once that time has passed. For a change you asked for in the
conversation, the notice ends **Send your message again then.**, and you send it again in the
conversation. Nothing holds you back before that time, because the limit may be raised sooner, but a
step started while the limit is still reached stops again. If your organization's own model
provider key reached its limit, see
[Model provider](/user-guide/engineering/agents/model-provider#a-session-is-paused-because-your-key-reached-its-usage-limit).

### To restart a run that stopped responding

If the agent stops reporting while it works, the session shows a warning that says how long, for
example **The agent hasn't reported for 14 min**, or **The agent hasn't started the run (dispatched
12:31)** when it never reported at all. It shows after 5 minutes without a report or any output, and
for a run that hasn't started, once the time a run has to start (10 minutes, more while a large
image downloads) has passed. It never shows while a cloud session is still
waiting for its runner.

Under it, the session says what it knows about the machine running the agent, and checks again
every 15 seconds:

- **Cloud runner · running · last heartbeat 12 s ago**: the runner is alive, so the agent itself is
  stuck, for example on a slow or stalled download. **Cloud runner · not responding since 12:44**
  means the runner itself has gone quiet.
- **Productmind agent my-laptop · not connected. Start `pm agent` there and the run continues
  where it left off**: your own agent has gone offline.
- **Last step: Cloning repositories, 12:31 · last output 12:32**: the last step the agent reported,
  and when it last wrote anything.

1. Read the line under **Restart run**. It says what a restart does for this session.
2. Choose **Restart run**.

The run stops, and the same run starts again from where it was saved: its conversation with the
agent, the session's working branch and the agent's notes.

- In the cloud, the run continues on a new runner. Changes the agent hadn't pushed to the working
  branch yet are lost, and a live preview on that runner stops.
- On your own Productmind agent, the run starts again on that agent while it's connected, and keeps
  its working copy. When that agent is gone, it starts on another of your agents, or in the cloud.

**Restart run** is available only while the run is silent. While the agent still reports, the line
under it says so. If the previous run is still stopping on your own agent, the session says so: quit
and restart `pm agent` there. To end the run instead, choose **Cancel session**.

The conversation shows who restarted the run, and why: for example **Run restarted by Ada Lovelace:
the agent hadn't reported for 14 minutes. It continues on a new cloud runner from its conversation,
the working branch and the session's notes.**

If the run stays silent for 45 minutes, the session fails with **Retry**, and a run you retry in the
cloud starts on a new runner.

### To build an approved plan

If a build didn't start after you approved the plan, the session shows **Build**.

1. Choose **Build**.

The agent starts building, and the status becomes **Building**.

If the plan changed after you approved it, the button reads **Re-plan** instead. It drafts the
plan again, for you to review and approve.

When your Pay-as-you-go balance can't pay for the step, **Build** and **Re-plan** are grayed out,
with the reason and the action that fixes it under the button.

When Productmind can't push to a repository, **Re-plan** and **Draft a plan** aren't held: they
say **The plan can run, but the build will be held until Productmind can push**.

## Permissions

| To | You need |
| --- | --- |
| Stop a turn or a preview, cancel a session or resume a cancelled one | **Sessions: Update** |
| Retry or restart a run, or build an approved plan | **Sessions: Update** |

## Related topics

- [Working in a session](/user-guide/sessions/working-in-a-session)
- [Starting a session](/user-guide/sessions/starting-a-session)
- [Live preview](/user-guide/sessions/live-preview)
- [Pull requests and reviews](/user-guide/sessions/pull-requests)
- [Productmind CLI](/user-guide/tools/productmind-cli)
