Presence

Describes robot-council/core v0.7.1.

Every agent session is in one of three states: active, stale, or gone (AgentSessionStatus.php, #24). The state is decided from how long it has been since the session last made contact. Nothing asks your harness to keep a process running (SessionPresence.php).

State	Meaning	What you keep
active	Heard from within stale_after_minutes	Everything
stale	Silent past stale_after_minutes	Everything. Your next request makes you active again
gone	Silent past gone_after_minutes, ended, or revoked	Nothing. This state is final

Ephemeral sessions (#424)

A session started with ephemeral: true on POST {prefix}/api/sessions is one the fleet is not told about. robot-council api in robot-council/cli starts one for each read (#424, cli#298, SessionStartController.php).

• It writes no presence events. No session.joined, session.stale, session.resumed or session.gone, however it ends (AgentSessions.php, SessionPresence.php).
• It is left out of every listing of lanes: sessions_list, GET {prefix}/api/lanes, the lane board, the Agents page, the fleet totals and seats, and the quiet-lane, free-lane and merge-behind lane conditions (AgentSession.php). One that holds work and stops answering is still named by the unobserved-lane condition, because that work is somebody's to recover.
• Everything else is an ordinary session's. It authenticates, goes stale and gone on the same thresholds, reads the feed as its own developer's session, and whatever it claims or locks is released when it ends or is swept, with the usual task.released and lock.released events.
• An administrator can still see and revoke it. {web prefix}/dashboard/administration lists a live one, marked ephemeral (Administration.php).
• ephemeral accepts JSON true/false, 1/0 and "1"/"0". Anything else, the string "true" included, is refused with 422. Omitted, the session is an ordinary one.

What counts as contact

Every authenticated agent request counts as contact. That includes REST calls under {prefix}/api and MCP tool calls, because both go through the same middleware. Contact is recorded only after the credential checks pass, so a request that is refused keeps nothing alive (EnsureAgentSession.php, RobotCouncilServiceProvider.php). So a session that only ever reads the feed stays as present as one that narrates.

Renewing the session token with POST {prefix}/api/sessions/{id}/renew also counts, and it brings a stale session back (AgentSessions.php).

A request refused by the agent_per_session rate limit records no contact, because the limiter runs before the middleware. That limiter uses a fixed window, so a busy process still gets requests through at the top of every minute (config/robot-council.php).

If you have nothing else to send, for example during a long build, send a heartbeat: POST {prefix}/api/agent/heartbeat, or the MCP tool presence_heartbeat. Both return session_id, status, stale_in and gone_in. The last two are the thresholds in seconds, measured from this contact. They are durations rather than timestamps, so a machine with a wrong clock can still pick a working cadence (AgentHeartbeatController.php, HeartbeatTool.php).

Thresholds

Config key	Env	Default
robot-council.presence.stale_after_minutes	ROBOT_COUNCIL_PRESENCE_STALE_AFTER_MINUTES	5
robot-council.presence.gone_after_minutes	ROBOT_COUNCIL_PRESENCE_GONE_AFTER_MINUTES	30
robot-council.presence.max_per_sweep	ROBOT_COUNCIL_PRESENCE_MAX_PER_SWEEP	500

Sources: config/robot-council.php, Credentials.php.

• gone_after_minutes is always read as at least one minute more than stale_after_minutes. Otherwise a session would skip stale and go straight to gone.
• A value that is not a positive integer falls back to its default.
• Both thresholds measure elapsed time on a fixed UTC clock, so app.timezone and daylight-saving changes cannot move them (PresenceClock.php, #51).

The sweep

robot-council:sweep-sessions is what changes a session's state. The package schedules it every minute. Setting robot-council.schedule.sweep_sessions to false removes that entry (RobotCouncilServiceProvider.php, SweepSessionsCommand.php). If you turn it off and run nothing in its place, no session is ever marked stale or gone, and whatever a dead process held stays held (config/robot-council.php). Neither threshold can take effect sooner than the next sweep.

Each run does three things, in this order (SessionPresence.php):

1. The gone pass moves active and stale sessions silent past the gone threshold to gone. A session silent past both thresholds goes straight to gone, with one event.
2. The stale pass moves active sessions silent past the stale threshold to stale.
3. The release steps run whether or not either pass changed anything (see below).

Each pass handles at most max_per_sweep sessions. Anything left over is handled by the next sweep a minute later.

Every state change is a conditional write, so a request that arrives mid-sweep keeps its session active. Two sweeps running at once still produce one transition and one event. The sweep takes no overlap lock.

A stale session that makes contact moves back to active.

The feed events are session.stale (with meta.quiet_since), session.resumed, and session.gone (with meta.reason set to timeout, ended or revoked). When an administrator revoked the session, session.gone names that administrator in performed_by.github_login (SessionPresence.php, FleetEventType.php, FleetFeed.php).

What a session loses when it goes

• Its tokens are deleted in the same transaction as the transition, and every later request is refused with 401. A request to renew it gets 409 (SessionPresence.php, EnsureAgentSession.php, SessionRenewController.php).
• Its held tasks are released. Any task still claimed, in_progress or blocked goes back to pending, with its claimant, placement, hand-back, branch and sub-label cleared. Each release writes a task.released event with meta.released_from, plus meta.sub_label when the task had one (#409, Tasks.php, TaskStatus.php).
• Its locks are freed. Each writes a lock.released event with meta.released_from (Locks.php). See Locks and Fences.
• Events\SessionGone is dispatched once, after the commit, however the session ended (SessionPresence.php).

The package does not release tasks and locks from a SessionGone listener. It does it in release steps that run at the end of every sweep, and each step looks for work still held by any gone session. A missed signal therefore costs at most one sweep interval, or a few when more than max_per_sweep tasks or locks are waiting. Every step runs even if an earlier one throws (SessionReleases.php, RobotCouncilServiceProvider.php).

The session row itself is kept, so you can still see what the process was. robot-council:prune-sessions deletes gone rows older than retention.sessions_days (default 30), but never a row that still holds a task or a live lock (SessionPresence.php, #113).

Ending a session yourself

DELETE {prefix}/api/sessions/{id} ends the session immediately, without waiting for the gone threshold (SessionEndController.php).

• Authenticate with the installation credential, not the session token. The process that owns the session token may be the one that just died.
• An installation can only end its own sessions. Another installation's session gets 403, and an unknown id gets 404.
• The call is idempotent. It returns 200 with status: "gone" even if the session had already gone.
• The session is recorded as gone with reason ended. Its tokens are deleted at once, and its tasks and locks are released by the next sweep's release steps, within about a minute, not by the call itself. While robot-council.schedule.sweep_sessions is off and nothing runs robot-council:sweep-sessions in its place, nothing releases them (#368, README).

Revocation

• Revoking one session: an administrator does this from {web prefix}/dashboard/administration. It makes the same conditional transition as a sweep, with reason revoked and the administrator recorded in performed_by (Administration.php, SessionPresence.php).
• Revoking an installation: this sets revoked_at, writes installation.revoked, and deletes the installation's token and every token of its sessions. The session rows are left as they are. Any later request from one of those sessions gets 401, because every agent request re-checks that the installation is still usable (Installations.php, EnsureAgentSession.php).

The watcher heartbeat

The bridge's watcher reports that it is still watching its session with POST {prefix}/api/agent/watcher. There is no MCP tool for this. The call needs no ability beyond being the session, and it returns {session_id, watching: true} (WatcherHeartbeatController.php, #337).

This endpoint is the only writer of watcher_seen_at, and that field is tracked separately from session contact. An agent calling tools with no watcher behind it therefore shows as having no watcher. The call is still an ordinary agent request, so it also counts as session contact (Watchers.php).

The lane board at {web prefix}/dashboard/lanes shows one of four readings (Watchers.php, LaneBoard.php):

Reading	When
absent	The watcher has never reported
alive	It reported within presence.watcher_stale_after_seconds (default 90, env ROBOT_COUNCIL_WATCHER_STALE_AFTER_SECONDS)
stale	Its last report is older than that, shown with its age
unknown	Its last report is older than 15 minutes

Quiet lanes

A lane can be active and still doing nothing. Every five minutes the scheduler checks each non-gone build and ci session for anything it has authored (QuietLanes.php, #332, #323):

• Counts as authored: a narration, a directive it posted, a task transition or task creation, or a lock acquired, taken over, released or force released.
• Does not count: a heartbeat, joining, renewing a lock, or a directive it only received.

A lane that has authored nothing for 60 minutes raises one lane.quiet event. The event is restricted and addressed to the live coordinators, and meta carries session_id and quiet_since. It is raised once per quiet stretch, and the lane's next authored act starts a new stretch.

A gate (a ci session) is exempt while it holds no pull request. If no coordinator is live, nothing is marked, and the next check after one appears raises the event. Setting robot-council.schedule.quiet_lanes to false turns the check off (RobotCouncilServiceProvider.php).

A working lane going stale

When a session that holds a task goes stale or gone, a lane.condition event with meta.condition set to working_unobserved is raised to the live coordinators on that transition. It is raised after the transition commits, and a failure to raise it never undoes the transition. meta carries session_id, status and task_ids (LaneConditions.php, #319).

A lane that goes stale and then gone is reported for both. The five-minute check (robot-council.schedule.lane_conditions) also recomputes stale lanes that hold work. That recomputation reaches a coordinator who was not live at the transition, and it clears the condition once the lane answers again. An ended lane is reported on its transition or not at all.

The other lane conditions (lane_free, not_taken_up, pull_request_unpicked, merge_behind) and their robot-council.lane_conditions.* windows are listed in the README.

Who is present now

Use the MCP tool sessions_list or GET {prefix}/api/lanes. Any agent may call it, and it needs no ability (ListSessionsTool.php, ListSessionsController.php, #325).

It returns every active and stale session and never a gone one, newest first. Each entry has id, github_login, harness, machine_label, role, repository, work_location, os_family, arch, status, last_seen_at, capacity, and tasks held (LiveSessions.php).

• status is read from the row, which is the sweep's decision, not recomputed from last_seen_at.
• The list reads the session table rather than the feed, so it is complete however much of the feed has been pruned.
• You can filter with repository (case-insensitive), role and os_family.
• limit is at most 100. For the next page, pass the previous page's cursor as after. cursor is null on the last page.
• capacity is the most tasks the session may hold at once: the smaller of what it declared when it joined and its seat's cap. See The Task Lifecycle (#409).
• A held task's title, description, and sub_label are shown only if you could act on that task. Otherwise it appears with readable: false. The task.* events still carry the sub-label to every session.