# Manage sessions

> Find a session, read where its work stands at a glance, and keep the list tidy with stars, labels and the archive.

The session list shows every conversation in the project, newest first, each marked with where its work stands.

![The session list.](https://iterada.com/docs/shots/sessions-list.png)

## Read the marks

The mark beside each session says where its work stands; hover it, or press and hold on a phone, to read it in words. A mark that names a step of the session's workflow - Spec, Implement, Iterada checks, Code review, Preview, Merge, Deploy - is the icon that step wears on the workflow in **Agent factory**, and while the step runs a ring turns around it. The open session wears the same mark beside its name at the top of the conversation.

| The mark reads | What it means |
| - | - |
| Agent is working | A turn is running: the Implement step, turning. You can close the tab. |
| Agent has a question | The agent needs a decision, or a plan waits for you. |
| Spec waiting for you | The agent proposed a spec and waits for you to accept, change or discard it. |
| Waiting for ... | A session of a plan is held until the sessions it was told to follow have finished their first turn. |
| Iterada's checks are running | Iterada is running your project's checks on the change; its mark turns until they finish. |
| A second agent is checking | Another agent is checking the change against its spec. |
| A step's name, followed by in progress | A step of the workflow the session runs, such as its checks or its review, is under way. |
| A sentence such as "This change is verified and ready" | The change is held and goes on by itself: it waits for Iterada's checks to start, or for the other sessions of its plan to finish changing files. |
| Waiting for your merge | The change is ready and this project waits for you to merge it. |
| Merged to, followed by your default branch's name | The change is on your default branch, not yet live. |
| Deploying to production | A deployment is running. |
| Deployed to production | The change is live. |
| Preview is ready | A preview of the change is ready to look at. |
| Rate limit reached | The agent's plan ran out for now; the work resumes by itself. |
| Waiting to retry automatically | The latest turn failed and Iterada will try it again. |
| Iterada continues this by itself | A turn of an Automated session failed; Iterada resumes it on its own a couple of minutes later, at most twice before the session's next merge. |
| Checks have been running for over an hour | Iterada's checks on the change are still going, or wait to run again because a run ran out of time. It goes on by itself. |
| Checks failed, so it was not merged | Iterada's checks still fail after it tried to repair the change. Ask for a fix, or merge it yourself. |
| Checks timed out after 4 hours, so it was not merged | No test failed, but the checks ran out of time each time they ran. Merge it yourself if you trust it, or ask for more work on it. |
| Not merged, followed by the reason | Iterada could not merge the change, for example because your default branch changed the same lines meanwhile. |
| Conversation ended with an error | The latest turn failed. Send a message to try again, or report it. |

## See where a session is

While a session moves by itself, the line under its name says what it is doing and for how long, such as Working or Iterada's checks are running. Otherwise the line is the agent's last sentence.

Open the session and the steps of its workflow sit under its name, the one it is on lit. A workflow with no step of its own for the merge and the deployment ends with Your merge and Deploy. While a turn runs, a banner over the message box says what the agent is doing, for how long, and when it last showed a sign of life. After a few quiet minutes with nothing running it turns to a warning, and Iterada restarts a turn that stays silent.

Press the line under the session's name to open **Session details**: the same facts one by one, plus its workflow, who last changed it and when, and its history.

## Point at the preview

When a change's preview is ready, it opens beside the conversation. Hide it with the arrow in its top corner and bring it back with the arrow at the right edge of the conversation; it comes back on the page it was showing. On a phone, press **Preview** over the conversation and it fills the screen.

1. Press **Point**, then click what should change, or drag a box around an area.
2. Type or say what you want in the note that opens, and press **Add note**. Add up to 12 notes per message: each waits above the message box with its number.
3. Send your message. The agent gets every note with where it sits in your product, and the next preview opens on the same spots with their numbers, so you check each one where you asked for it.

Once your change is live, the panel shows your real product instead, marked **Live**. Pointing works the same way, but with **Point** off your clicks happen for real. On Iterada's own project, press the pointer beside the paper clip under the message box and point at Iterada itself.

While **Point** is off, use the preview normally: open pages and click around. What you opened and clicked on the way tells the agent how to reach the same place. **Phone** and **Tablet** show those screen sizes; **Fit** uses the space beside the conversation. App sign-ins and storage work when your installation can give the preview its own web address.

## Find a session

- The menu at the top of the list switches between **Active**, **Inactive**, **Starred**, **Drafts** and **Archived**, each with its count. Sessions you have not touched for a while move to Inactive by themselves. **Drafts** holds messages you saved without sending.
- **Find or filter sessions** searches by what sessions say and filters them by progress (**In progress** or **Completed**), by **Label** and by **Last changed by**: Iterada or a person.
- **Sessions** and **Automated** above the list separate your own work from the sessions Iterada started from findings and artifacts. Automated has its own Active and Archived.
- While any session in the tab has failed, **Resume all failed sessions** appears above the list. A session whose change was not merged counts too: one whose default branch changed the same lines meanwhile, or whose checks still failed after Iterada's repairs. One press asks each of them to carry on from where it failed: a change your default branch moved past is brought up to date with it, a change whose checks failed is repaired, and any other turn picks up where it stopped.

## Keep it tidy

Open the three-dots menu at the top of a session, or press and hold a row in the list (right-click works too):

- **Star session** keeps it at hand under Starred.
- **Labels** gives it up to three names of your own, each with a colour, and the search filters by them. Every label shows on the session's row. When you send a message, Iterada adds the labels you already use that fit it. When none fits clearly, it shows **Suggested labels** below the session's top bar once, in the same editor as **Labels**: take a suggestion off with its cross, pick another of your labels from the list or type a new name, then press **Add labels**, or press **Not now**. A label you take off a session is never added to it again.
- **Archive session** puts it away; **Restore session** brings it back. On a computer, pointing at a row in the list also shows an Archive button at its end. On a phone, swiping a row to the right archives it too.
- **Pause** and **Resume**, on a row you press and hold (or right-click), work on a session without opening it. **Pause**, while the session is working, stops the agent where it is and lets the next waiting message run. **Resume** carries on a session you paused or one that failed: a paused turn picks up from where it stopped; a failed session carries on as **Resume all failed sessions** would.
- **Cancel**, while the session is working, waiting to retry or paused, stops it and cancels every message waiting its turn and any paused turn.

**Archive deployed sessions** above the list puts away every session in the tab whose work is already live. If one of them opened sessions that are not live yet, it asks whether to archive those too or keep them open on their own.

Iterada also tidies by itself. A fix session it opened from a quiet-hours finding is archived as soon as the fix is live, unless you wrote in it. With quiet hours set to fix what it finds, **Platform tidying** also closes finished sessions in each quiet-hours run - merged, deployed and quiet for a week. See [Work in quiet hours](https://iterada.com/docs/overnight#after-quiet-hours).