Following a live agent session

When an agent picks up a task, CodeHerder spawns a clean session for it and starts a terminal process on an eligible device. The Sessions view gives you a live window into every session running right now, so you can watch progress, step in when needed, and review what a finished session accomplished.

Sessions appears in the sidebar of every workspace. A number badge next to the label counts the sessions running right now — it updates automatically as agents start and finish work.

Click Sessions to open the full page. Below the filter bar sits the session list. A second, narrower list — Sessions needing attention — appears above it, but only when CodeHerder has something to flag.

Sessions needing attention

Sessions needing attention can show you something the list below can’t: a session still running after its sandbox already finished. See When a session goes quiet for why that happens.

This section shows only the live sessions CodeHerder has flagged stale — not every live session in the workspace. It stays hidden entirely while nothing is flagged, and appears the moment CodeHerder flags one.

Columns:

Column	What it shows
Session	The session itself — click through to its page.
State	The session’s live-state badge, plus a warning badge naming why CodeHerder flagged it. See When a session goes quiet below.
Agent	The agent running the session.
Device	The device the session is running on.
Last contact	When the device last reported in. Filled in only on a stale row; every other row shows a dash.

A filter bar sits above the page’s lists, with a Live / Open / All control. It doesn’t narrow this section — that control belongs to the sandbox list further down. The search box is the exception: it narrows both sections at once, since they read the same query.

The sandbox list

Below Sessions needing attention is a second list, with its own filter and its own heading that changes to tell you what you’re looking at. This list shows sandboxes — the durable workspace each agent (or you, in a session you start yourself) works in — not individual session processes. A sandbox is durable and can hold more than one session process (a run) over its life: an agent’s process can restart inside the same sandbox, so one sandbox row can represent several runs.

Heading	When	What it shows
Sandboxes running now	Live selected (the default)	Only sandboxes with an active terminal right now.
All open sandboxes	Open selected	Every sandbox that hasn’t finished yet, live or idle.
All sandboxes	All selected	Every sandbox, including ones that already finished or were abandoned.

The list loads a batch of sandboxes at a time and pulls in more automatically as you scroll to the bottom. A Load more link also appears there, as a manual fallback if you’d rather click than scroll. There’s no fixed cap — keep scrolling (or clicking Load more) to reach every sandbox that matches your filters.

Columns:

Column	What it shows
Type	For a task-driven sandbox, the task’s own type badge (for example `story` or `bug`), or a plain Task badge if the type isn’t known — plus a second Task badge next to it; for a session you start on a device, a single Remote badge.
State	The sandbox’s own durable lifecycle state, plus — whenever the sandbox itself isn’t live — a second badge labelled last run, showing how its last run ended. These are two different things; see Sandbox state vs. a run’s outcome below.
Agent	The agent running (or that last ran) in this sandbox.
Working on	The task this sandbox is working, shown as `<Stage> - <task title>`; a task-free sandbox keeps its own title or branch name.
Device	The device the sandbox is running on.
Repo	The repository this sandbox’s isolated worktree is checked out from.
Cost	The model spend so far for this sandbox. A smaller second line, task $X, shows the lifetime spend across every sandbox of that task — not just this one.
Actions	A ▶ Drop in button while a sandbox is live; otherwise a link to the last run’s own session page, showing N runs whenever the sandbox has held more than one.

Filter control:

Live / Open / All — a three-way switch; Live (the default) shows only sandboxes with a running terminal, Open adds idle-but-unfinished sandboxes, and All adds finished and abandoned ones too.

Sandbox state vs. a run’s outcome

A sandbox’s own State badge and a session run’s outcome answer two different questions, and the list shows both:

Sandbox state is the durable sandbox’s own lifecycle: it moves through Provision → Ready → Active → Completing → Done, or ends Abandoned. A sandbox for a session you start yourself can also read Stopped — see Start a session on a device for what that means. An Abandoned sandbox was torn down without merging — it says nothing on its own about whether the run inside it actually finished its work.

A run’s outcome — shown as the second badge, labelled last run, next to the sandbox’s own state, and everywhere else an individual session is shown (a session’s own page, a task’s Workflow rows, and the session lists on a device’s, a repo’s, and an agent’s page) — is CodeHerder’s own answer to “did this run finish its work?”:

Badge	What it means	What usually causes it
Starting	The session is being set up.	—
Running	The session is live right now.	—
Completed	The work was handed off.	The task’s stage advanced, or the session’s sandbox was retired with Mark done.
Released	The session was deliberately stopped before finishing — not a failure.	Stop, Abandon, a spend cap, a session you started that was stopped or idle-parked, an AWS Spot reclaim on a cloud device (see If AWS reclaims the instance), or CodeHerder clearing a session whose stage had already moved on.
Incomplete	The agent’s process ended on its own without handing the stage off.	—
Failed	The process ended badly.	A non-zero exit without handing off, a stalled session CodeHerder replaced, or a session that failed to start.
Lost	Contact with the device or the process was lost.	The device stopped reporting, the device’s connection dropped, or the session’s sandbox had already retired. See When a session goes quiet below for how CodeHerder gets there.

Hover any badge for a one-line explanation. See Why a session ended below for how this differs from the Reason row.

Whichever vocabulary a badge uses, the green dot is the one signal that means the same thing everywhere: an agent process is running right now.

Queued and leftover sessions

Two badges appear above the list whenever there’s something worth your attention, even with Live selected — they cover sandboxes that don’t have a running terminal, so they’d otherwise be invisible in the default view.

“N queued for a slot” means sessions have been set up and are waiting for a device slot to open — every device only runs so many sessions at once (see Concurrency and capacity). A queued session starts automatically the moment a running session on that device finishes and frees its slot; you don’t need to do anything. If this count is high or keeps growing, it’s usually the answer to “why hasn’t my new task started?” — see Why isn’t my task moving? for the full diagnosis.

“N on finished tasks” is a warning: it means N sessions are still open even though the task they belong to already finished, was cancelled, or was abandoned. A session like this isn’t doing anything useful — it’s just holding a sandbox slot that another task could be using. The same warning appears on the affected row itself (for example, “task done”) so you can spot it without checking the badge count first.

This is a different count from the “N stale” badge in the page header — see When a session goes quiet below. They watch for different problems on different sections of the page, so don’t mix them up.

When a session goes quiet

CodeHerder watches every live session for two warning signs. It flags a row in Sessions needing attention when it spots one:

Device silent — the session’s device hasn’t reported in for about fifteen minutes.
Sandbox retired — the session is still running. Its sandbox has already finished.

Device silent needs about fifteen minutes of device silence. A brand-new session gets that same window before the check can flag it. Sandbox retired has its own five-minute grace period, so an ordinary teardown never trips it.

A flagged row shows a warning badge next to its state. Its Last contact column shows when the device last reported in. The page header carries its own warning badge, reading “N stale,” when at least one live session is flagged.

Being flagged is a warning, not a verdict. CodeHerder rechecks every live session about every thirty seconds and marks a still-flagged session Lost. A Device silent flag clears on its own if the device reports in again before the next check. So a flagged session doesn’t always end up Lost. A Sandbox retired flag doesn’t clear this way — that check doesn’t look at whether the device is connected. If your workspace has a webhook set up, being marked Lost fires the session.lost webhook — see Webhooks.

You don’t need to do anything when a session goes Lost. CodeHerder recovers on its own — see Why a session ended below for what that looks like.

Retiring a leftover session

Open the leftover session’s task and find the Sessions panel on the task’s detail page — this is the same panel where you start a session as well as retire one:

Launch session appears when the task has no live session, and sets up a fresh session for its current stage.
Activate appears on a session that’s already set up but hasn’t started running yet, and brings its terminal online.
Finish session wraps up a session that’s still actively working, moving it toward a normal close instead of abandoning it. The stage’s pinned assignee (or a workspace admin) can use this one.
Mark done appears once a session has moved into that closing state — typically right after Finish session — and closes it out for good: it stops the agent process if one is still attached and frees the slot, without touching the task’s own workflow stage. It sits at the same permission tier as Abandon, and the two appear side by side at this point. The underlying session ends Completed.
Abandon tears down the session’s sandbox immediately, without merging anything, and frees its slot. This is the right control for a leftover session — it’s terminal and can’t be undone, so only a workspace admin or owner can use it. The underlying session ends Released — a deliberate stop, not a failure.

CodeHerder only shows you the controls you’re allowed to use, so if you don’t see Abandon on a session, you’ll need an admin or owner to retire it — see Why a control is missing.

If a device looks fully busy but nothing seems to actually be running on it, that’s usually a different problem — leftover worktree slots on the device itself, not a leftover session. See Reclaiming stuck worktree slots in Managing your devices for that case.

Reaching a session from a task

Every task’s detail page has a Workflow view that shows which session ran each stage. If that session is still live, the row shows a ▶ Drop in button — clicking it opens the session’s live terminal. If the session has finished, the row shows a View → link that takes you to the same page with its recorded summary instead.

The Tasks list offers the same shortcut: a row whose task has a live session carries its own ▶ Drop in button.

The live-terminal page

Opening a live session via ▶ Drop in (from the session list, the Tasks list, or the task’s Workflow view) connects your browser to the agent’s running terminal.

Who can drop in: opening the terminal, using the Send box, viewing scrollback, and pressing Stop all require a human who is either a workspace owner or admin, or the session’s agent’s operator (the human who created that agent). Agents can’t attach to a session at all. Without that access, the connection pill reads no permission and a short notice explains who can attach instead — the page doesn’t sit there retrying.

The page header shows a connection status pill:

Status	Meaning
connecting…	Opening the connection for the first time.
connected	The terminal is live and receiving output.
reconnecting (attempt N)	The connection dropped briefly; the page is retrying automatically, counting each attempt.
session completed / session released / session incomplete / session failed / session lost	The session has ended — the outcome named in the pill is the same one described in Sandbox state vs. a run’s outcome above. The terminal is no longer attachable; a banner below explains what happened, and for a lost session, the device-level reason if one was recorded.
rejected: …	The connection couldn’t be established — the pill names the cause, for example `rejected: auth expired`. Sign in again and reopen the session.
no permission	You’re not a workspace owner or admin, and not this session’s agent’s operator — see Who can drop in, above, for who is.

While a session is live, a Stop button appears in the header for anyone who can drop in (see Who can drop in, above — everyone else just doesn’t see the button). Clicking it sends a stop signal to the agent’s terminal process. Use this when you need to halt a session that is going off-track. The button disappears once the session has finished. A session you stop this way ends with a Released outcome, not a failure — see Sandbox state vs. a run’s outcome above.

Tip: If clicking or scrolling in the terminal seems to do nothing, a full-screen program running inside it has likely captured the mouse. Hold Shift while clicking or scrolling to use the page’s own scrollback and selection instead.

Sending input to a live session

There are two ways to send input to a running session, and they behave differently for the team’s audit trail.

Typing directly into the terminal sends keystrokes straight to the agent’s process. This is fast, but the keystrokes are not recorded in the team activity feed — a banner directly above the terminal reminds you of this whenever a session is live. On a phone, an on-screen key row below the terminal (Esc, Tab, ⇧Tab, and the four arrow keys) — pinned in place as you scroll — lets you answer an agent’s interactive prompts without a physical keyboard; these keys count as direct typing and are not recorded either — the banner covers both.

Using the Send box (below the terminal) sends text through CodeHerder’s API. This input is recorded in the activity feed, so the team can see what you sent and when. The Send box carries plain text — newlines and tabs survive — but it can’t send Escape or other control keys; use the terminal itself (typed or via the on-screen key row) for those. Prefer the Send box when you want a permanent record of your intervention. Click Send input (audited), or press Ctrl+Enter (⌘+Enter on a Mac). Enter on its own adds a new line. After your text, CodeHerder presses Enter in the agent’s terminal, so the agent receives it as a submitted line. The same Send box appears when you expand a live session’s row on an agent’s page, for people who are allowed to send input.

Tip: For routine nudges you want your team to see — clarifying a requirement, redirecting the agent, or appending context — always use the Send box. Reserve direct terminal keystrokes for quick interactions where a record isn’t important.

The CLI has an equivalent for the Send box: ch session input, or ch session ask if you want to wait for the agent’s reply — see Sessions from the command line for the full commands.

Finished sessions

When a session ends, its terminal becomes unavailable. Navigating to a finished session — via View → on a task’s Workflow panel, or via a sandbox row’s run link in the All sandboxes list — shows the session’s recorded summary:

Agent — which agent ran.
Working on — which task the session was working, if any.
Stage — which workflow stage it was activated for.
State — its recorded outcome (see Sandbox state vs. a run’s outcome above).
Started and Ended — when it started and when it ended. For a session in the Lost state, the second row reads Lost at instead.
Duration — how long it ran. Omitted for a Lost session, since it was never observed stopping.
Exit code — how the process exited, when one was recorded.
Reason — why the session ended; see Why a session ended below.
Repo and Device — which repository it worked in and which machine hosted it.
Cost — the total model spend this session incurred, with a smaller breakdown of generation spend versus cache-read spend, the number of turns, and the cache-hit percentage.

This summary doesn’t include what the run printed as it ended. For that, use ch session tail from the command line — see Sessions from the command line; the web app has no equivalent view.

A task session’s page also carries a Skills section reporting whether each skill enabled for the workspace actually reached this session — see Skills for what each outcome means.

Why a session ended

The outcome badge (see Sandbox state vs. a run’s outcome above) and the Reason row answer two different questions. The outcome is the classification — completed, released, incomplete, failed, or lost. The Reason is free text describing what happened, when CodeHerder recorded one.

A session records why it stopped, and CodeHerder shows that reason in three places: the Reason row above, the banner on a lost session’s page (which says so explicitly when no reason was recorded), and as the detail on the “session ended,” “session killed,” or “session connection lost” entries in a task’s Activity timeline and the workspace activity feed.

The reason is a short note describing what happened — for example, that the device running the session dropped off and missed its check-ins, that the device came back online without reporting the session it had been running, that the session was stopped while its device was offline, or that CodeHerder replaced a session that had stalled with a fresh one. The exact wording varies by case.

One label is worth calling out because it looks like it disagrees with the outcome badge: the activity timeline calls an operator’s Stop “session killed,” while the session’s own badge reads Released. Both describe the same event — “killed” is what happened to the process, “Released” is how CodeHerder classifies the outcome — so seeing both isn’t a bug.

You don’t need to do anything for CodeHerder to recover: if a session’s stage is left without a live session, CodeHerder clears the dead sandbox on its own and the stage gets staffed again — which is why a task’s Workflow view can show more than one session for the same stage over its lifetime. The replacement session picks the stage up from where the work stands in the task’s sandbox. If a task still isn’t moving after that, see Why isn’t my task moving?.

What this session did

Every session page — live or finished — includes a What this session did section. This shows the meaningful actions the session took on its task, drawn from the event log: status advances, comments it posted, blockers it filed or resolved, and when it started and finished. The notes the session left as hand-off comments appear here too, giving you its own account of the work.

No chat transcript is stored — the event timeline is the durable record of what happened; see Activity feeds for how that record shows up on the task itself and around the workspace.

For the task list and its live-session indicators, see Finding and tracking your work. For agents that pause mid-run waiting on a human decision, see When an agent needs your input. For commenting on tasks and reading hand-off notes, see Collaborating. For understanding model spend across sessions, see Understanding costs. For sessions you create yourself, with no task behind them, see Start a session on a device. For finding, watching, and steering a session from the command line, see Sessions from the command line.